DIRSCAN by Donald L. Wallace

Copyright 1997 by Donald L. Wallace.

OVERVIEW

DIRSCAN provides a simple, component-based way for your Delphi program to
search through a directory tree in order to look for file(s) which conform
to a file name wilcard specification and a possible test of contents.

DIRSCAN is a non - visual VCL component that is source code compatible
with both Delphi 1 and Delphi 2.  DIRSCAN encapsulates the Windows API
functions FindFirst and FindNext to recursively scan subdirectories.

I offer DIRSCAN freely to the Delphi programming community. Use DIRSCAN in
any way you like, including educational, commercial or personal use.
Frankly, I think DIRSCAN has greater value as self-promotion and as a
goodwill token than as a money making product.  Just don't take credit for
writing it, and include the copyright notice in any source code into which
you embed DIRSCAN!

USING THE TEST PROGRAM

Unzip the ZIP file to a directory.

Install the file TDIRSCAN.PAS to your component palette. Refer to Delphi
product documentation for assistance.

Load the project file DIRSCAN.DPR.

Run the project.

The program allows you to exercise the directory scan component. Enter a
path, filename to search for, and press 'Scan' to start a search.

TECHNICAL REFERENCE

Source for component: DIRSCAN.PAS.

Component Name: TDirectoryScan

Properties

Directory : String

You set this property to specify the top most directory path that is to be
scanned.  'Directory' should be specified in the standard drive letter -
colon - backslash - path format. In Win32, do <not> use double quotes to
surround long path specifications that contain spaces when creating a
value to place into 'Directory'.  It is <not> recommended to use a path
starting with a relative specification (IE, a path such as ..\Mydir)

FileName : String

You set this property in order to specify the wildcard for files to be
matched. If not set, the default used by the component is *.* (all files.)

Subdirectories : Boolean

You set this property to control whether the control will scan
subdirectories. Default is TRUE.

CurDirectory : String

Read-only. This property will contain the current directory path being
scanned by the component. This property is useful only within the
OnProgress event handler.

TotalCount : Integer

Read-only. This property will contain the current number of files which
have been matched by the component. This property is useful only within
the OnProgress event handler.

Events

procedure OnProgress(Sender : TObject;path : String);

Purpose: OnProgress is called every time the component scans a new
directory (when the component first gathers directory paths) and every
time the component scans a new file. OnProgress can update a user
interface with current scan information. See CurDirectory and TotalCount
properties.

Procedure OnVerifyFile(Sender : TObject;path : String;
                       stream : TFileStream;TimeStamp : TDateTime;
                       var PassFlag : Boolean);

Purpose: OnVerifyFile is called every time the component locates a file
which matches the 'FileName' property. The purpose of OnVerifyFile is to
allow your code to determine if a file has a date stamp or contents which
make it eligible to be included as a 'found' file. 'path' is the fully
qualified file name; 'stream' is opened already in read mode, sharing
enabled, for the file passed in 'path', with the file pointer at the start
of the file. 'TimeStamp' is the last update time of the file.  'PassFlag'
should be set TRUE by your code on exit if the file is to be used, or
FALSE if the file is to be ignored. If FALSE is returned, OnProcessFile
will not be called by the component for the file.

(NOTE: If OnVerifyFile is <not> set to an event handler, the scanning
process will execute much more quickly than if OnVerifyFile is set. The
reason for this speed difference is that every scanned file has a file
handle opened for it per the 'stream' argument when an event handler is
set for this event type.  Also, every file that matches 'FileName' will be
accepted if there is no OnVerifyFile handler set.)

procedure OnDirList(Sender : TObject;paths : TStrings);

Purpose: OnDirList is called when the component has gathered all
sub-directories of the 'Directory' path. Every entry in 'paths' is a
subdirectory of 'Directory' which will be scanned for instances of
'FileName' after OnDirList returns. Subdirectories are listed in 'paths'
immediately following their parent directories.  Your code may perform any
valid manipulation of 'paths', including insertion or deletion of entries,
or copying of the contents of 'paths' to other storage.

procedure OnProcessDirectory(Sender : TObject;path : String);

Purpose: OnProcessDirectory is called every time the component scans a new
directory or subdirectory which contains a matching file.
'path' will contain the directory name. OnProcessDirectory will be called
just once per each directory that contains a matching file.

procedure OnProcessFile(Sender : TObject;path : String);

Purpose: OnProcessFile is called every time the component locates a
matching file. 'Matching' is defined as matching the property value last
set for 'FileName' plus being accepted by OnVerifyFile if OnVerifyFile is
set. 'path' will contain the file name specified as a full path
specification.

Methods

Function Execute : Boolean;

Purpose: The application calls 'Execute' in order to perform a scan for
files which match the specifications passed in properties 'Directory' and
'FileName', and which pass the optional test which may be performed by the
event handler 'OnVerifyFile'.

'Execute' returns TRUE if at least one matching file was located, FALSE if
none. 'Execute' also returns immediately with the value FALSE if 'Execute'
is called re-entrantly (that is, while the same component is already
running the 'Execute' method).

Procedure Cancel;

Purpose: The application calls 'Cancel' in order to force the
currently-executing method 'Execute' to return immediately. Typically a
call to method 'Cancel' would be invoked by a button press. If 'Cancel' is
called when 'Execute' is not running for the component, then nothing will
happen.

DELPHI 1 / DELPHI 2 DEPENDENCIES

There are the following areas of difference between Delphi 1 and Delphi 2 
usage.

- If built with Delphi 1, all file names and path names collected will be 
in the 8.3 character "classic DOS" format, even if the program is run in 
a Win32 system supporting long file names. Long path names will be 
translated into 8.3 character equivalents. In Delphi 2, all file names and 
path names that are collected. may potentially be long file names with 
embedded space characters.

- There is no 'Trim' function in Delphi 1, so the function is provided for 
Delphi 1 as conditionally compiled code.

- Delphi 1 strings may only be 255 characters or less. There is one 
conditionally compiled test to guard against excessively long file names. 
I have not tested the program exhaustively against long path name 
problems.

ABOUT THE AUTHOR

I am an independent consultant available for software development projects
and technological mentoring in Delphi, VB, and C++. Need a VCL
developed? I can do this sort of work for your organization. Based in
Ohio, available for consultation.  Please email directly to Compuserve
71247,3221, or donaldw@your-net.com for details.
